qacli analyze

既存のPerforce QACまたは、CMAプロジェクトの全体または、部分の静的解析を実行します。


使用方法

analyze  [-P <directory>] [-K <config name>] [-C <solution-name>] [--cma-project <project-name>] [-j <n>] [-u] [--use_disk_storage] [-r] [--reuse_db] [-R] [-I] [--repeat <n>][--retry <n>] [-o <output-path>] [-T] [-D] [-s] [--force-complete] [-g] [-c] [-f] [-l <cct-file>] [-F <filelist>] [-b <script>] [-a] [--] [-h] <source-file>


詳しい説明

解析はファイル単位、Perforce QACプルジェクト全体または、CMAプロジェクト（一連のPerforce QACプロジェクト）に対して実行することができます。

デフォルトでは、すべての従属ファイル（または、設定ファイル）を含む変更されたファイルのみ再解析されます。

ファイルおよびプロジェクトは消去されることがあるでしょう。その場合解析結果は削除されます。これは事実上次回コマンドが実行されたときに解析を強制します。

すべての例は、１設定をもつデフォルトのPerforce QACプロジェクトです。 複数の設定をもつプロジェクトを使用する場合（複数の設定を持つプロジェクトの作成を参照）、非デフォルト設定を指定する場合は、--config <Config Name> option　を使用してください。

オプション

オプション名、短縮形 デフォルト 説明
‑‑assemble‑support‑analytics, ‑a   '.arc'ファイル、プリプロセス済みソースファイル、オプションファイルを含む各解析失敗ファイルに対する、圧縮アーカイブを作成します。
‑‑build‑command, ‑b   実行されるとコードをビルドするスクリプトへのパスを指定します。ビルドが実行されると、ソースファイルや依存性情報が抽出され、指定のPerforce QACプロジェクトに追加された後、解析されます。
‑‑clean, ‑c   解析を任意で実行する前に、すべての解析結果を指定のプロジェクトから削除します。 'cma-project'　オプションが指定されている場合は、解析に関わったすべてのPerforce QACプロジェクトが削除されます。
‑‑cma‑solution, ‑C   クロスモジュール解析を実行するため、CMA プロジェクト名を指定します。このオプションを使用すると、クロスモジュール解析が実行される前に、プロジェクトに関わるすべてのモジュールPerforce QACプロジェクト）に対し解析が行われます。CMA （CMAプロジェクトの最初のモジュールがデフォルトで使用されています）の結果を保存するためのプロジェクトを指定するには、--qaf-projectオプションを使用してください。
‑‑config, ‑K   複数の設定を持つプロジェクトに対しどの設定を使用するかを指定します。指定がない場合は、「デフォルト設定」が使用されます。
‑‑disable-sync, ‑D   結合されているValidateプロジェクトで解析が開始される前の　RCF　の同期を無効化します。
‑‑file‑based‑analysis, ‑f   指定したファイルまたは、プロジェクトの解析を行います。このスイッチは、Raw-sourceまたはcma-project 解析の実行時に自動で有効になりますが、それ以外の場合は手動で有効にする必要があります。cma-project を削除、解析したい場合は、このオプションを明示的に指定する必要があります。
‑‑files, ‑F   解析するファイルのリストがあるファイルへのパスを指定します。指定がない場合、プロジェクトの全ファイルが解析対象となります。
‑‑force‑complete   早期終了に繫がる可能性のある処理段階でのエラーが起きても全ファイルの解析の処理を強制します（ライセンスチェック障害など）。--stop-on-fail と同時実行はできません。
‑‑generate‑preprocessed‑source, ‑g   解析される各ソースファイルに対し、ファイルの出力ディレクトリに前処理ソースファイルを生成します。
‑‑help,‑h   使用方法の情報を表示し、終了します。
‑‑ignore‑rest, ‑‑   このフラグ以降のラベルの付いた引数をすべて無視します。
‑‑inter‑tu‑dataflow, ‑I   翻訳単位間データフロー解析を実行します。
‑‑jobs, ‑j   解析時に同時に実行する処理の最大数を明示的に指定します。このオプションのパラメータはすでに設定されている値（qacli config cpu --set <jobs>）および、システムデフォルト（通常コアの数 - 1）をオーバーライドします。
‑‑language‑cct, ‑l   raw-source 解析に使用するCCTへのパスを指定します。noneが指定されている場合、デフォルトで　'QAC_Generic_C++.cct' が使用されます。
‑‑output‑progress, ‑o   指定したファイルに解析進捗状況が送信されるよう設定します。
‑‑qaf‑project, ‑P   実行する有効なPerforce QACプロジェクトへのパスを指定します。
‑‑raw‑source, ‑R   解析対象ファイルをPerforce QACプロジェクトの範囲外に設定します。この設定は、設定上の問題点のデバッグを行う際に役に立ちます。ファイルは、解析設定の「解析したファイルのプリプロセス済みソースファイルを生成する」を有効にして生成されたファイルで、'.i'ファイルでなければなりません。
‑‑retry 3 ライセンス障害または、パーサが予期しないリターンコードを返したために解析が失敗した場合、短い待機の後最大 'n' 回まで再試行できます。デフォルトの再試行回数は、3回に設定されています。この機能は試行回数をゼロに設定することで無効化できます。
‑‑show‑timings, ‑T   ([nd ]HH:MM:SS)のフォーマットで解析のタイミング情報を表示します。'nd ' は日数を表すので、1以上であるときのみ表示されます。
‑‑stop‑on‑fail, ‑s   最初の解析の失敗が発生すると解析を中止します。--force-complete と同時に使用できません。

例

Perforce QACプロジェクトの解析

Perforce QACプロジェクトに対して解析を実行する場合は、以下のコマンドを実行します。 

qacli analyze -P <directory> --file-based-analysis 

このコマンドは最後に解析が実行されてから後に変更のあったファイル（ソースファイル、依存ソースファイルまたは設定ファイル）すべてを解析します。


すべての解析結果をプロジェクトから削除するには以下のコマンドを使用します。 

qacli analyze -P <directory> --clean 

これらのオプションは効果的にプロジェクトをきれいにし、再解析をするために組み合わせることができます。 

qacli analyze -P <directory> --file-based-analysis --clean
コマンドウィンドウで現在実行中のコマンドを強制終了したい場合は、'Ctrl + C' を使用します。

Perforce QACプロジェクトの解析

Perforce QACプロジェクトに対して解析を実行する場合は、以下のコマンドを実行します。このコマンドは最後に解析が実行されてから後に変更のあったファイル（ソースファイル、依存ソースファイルまたは設定ファイル）すべてを解析します。 

qacli analyze -P <directory> --file-based-analysis 

選択的にファイルを解析する

コマンドラインで　double-dash ( -- ) オプションの後にファイルを指定することで単一ファイルを直接解析することができます。 

qacli analyze -cf -P . -- src/test_1.cxx

絶対パスまたは、ソースルートに関連している場合は相対パスを使用することができます。詳しくは
qacli project roots --listを参照してください。

複数のファイルを解析したい場合、テキストファイルに各ソースファイルへのパスを1行に1パスずつ、つまりfilelist の形で配置しなければなりません。

ファイルファイルリストにあるファイルを解析するには、以下のコマンドを使用します。 

qacli analyze -P <directory> -f --files <path-to-filelist> 
このオプションはCMAプロジェクトでは使用できません。

翻訳単位間解析

データフロー解析は通常はTU（翻訳単位）レベルで実行されます。つまり、すべての従属するヘッダファイルを含む単一ソースファイルです。

全プログラムレベルでデータフロー解析を有効にするには、以下の --inter-tu-dataflow オプションを追加します。 

qacli analyze -P <directory> -f --inter-tu-dataflow 

設定した　df::inter 　の値がゼロでないこと、df::query_timeout　が10より大であることを確実にしてください。これには、適切な値を設定オプションに自動的に入力する　'深さ'の設定を使用することができます。

このオプションはCMA　ソリューション　（例：　--cma-solution <solution-name>）では使用できません。
翻訳単位間データフロー解析の詳細については Perforce QAC データフローコンポーネントマニュアルを参照してください。

障害時の操作

以下のコマンドは、ライセンスチェックでエラーが発生しても、ファイルの処理をし続け、処理したファイルごとに進捗情報をレポートし続けます。 

qacli analyze -P <directory> -f --force-complete

以下の　switch　は最初のファイル解析の失敗の後に予定されている解析を中止するために使用します（解析がすでに始まっているものに関しては解析を完了します）。 

qacli analyze -P <directory> -f --stop-on-fail 

ネットワークの安定性および/または、ユーザのライセンスの使用限度によりますが、これはライセンス障害による解析の失敗または、利用可能な使用マシンのリソースによるパーサ障害による解析の失敗の可能性があります。

デフォルトでは最初の障害後3回まで解析を試みることができます。--retry オプションでこの再試行の回数を設定することができます。例: 

qacli analyze -P <directory> -f --retry 5 

この設定でライセンスまたは、パーサの障害が起きた場合、短時間の待ち時間で５回までファイルの解析を再試行することができます。ゼロと設定すると再試行を解除します。

--force-complete 　および　--stop-on-fail 　オプションは　同時に使用できません。

進捗状況のモニタリング

ファイルが解析されると進捗状況はコンソールに出力されます（進捗状況の出力を参照してください）。ソースファイル解析の進捗状況を追加でファイルに書き込むことができます。このファイルは処理された各ファイルの１行出力で、解析の進捗状況を正確に測定するために監視することができます。

最後の行は、Progreess(<label>) で始まり、3% 解析が進むごとにドット「.」 が表示されます。終了すると最後に「完了」と表示されます。例： 

qacli analyze -P <directory> -f --output-progress <output-path> 

デフォルトでは、解析のデルタタイムは表示されません。デルタタイムを出力（コンソールとファイル両方）に追加したい場合は、--show-timings　を指定します。

この設定で、各ファイルの解析にかかった時間が以下の形式で出力に追加されます。 

([nd] HH:MM:SS) 

'nd'は日数（0以上のときのみ表示されます）、 HH:MM:SS は、解析が完了するのにかかった時間の時間、分、秒の表示です。 

qacli analyze -P <directory> -f --show-timings
Progress(Cleaning): .................................... done
/home/cartman/sample_inspect_c/src/inspect.c:qac:0:1:0 (00:00:01)
Progress(File-based Analysis): ........................ done (00:00:02)
        

各ファイルの解析にかかった時間が表示され、さらに、コマンドの最後に合計の解析時間も表示されます。

  • 時間は、直近の秒の単位に四捨五入されます。
  • 個々の時間は解析にかかった時間のみで、Perforce QACが各ファイルを処理するのにかかった時間は含まれません。
  • 上記の2点から、すべての個々の時間の合計が表示された合計の解析時間と一致しない可能性があります。

同期と解析の同時処理

同期（Perforce QACプロジェクトにファイルを追加する）とそのファイルの解析を同時に行うことができます。 

qacli analyze -P <directory> --build-command <script> 

通常、ビルドコマンドであるこのスクリプトは、実行されそのビルドは監視されます。ファイルが検出されるごとに、プロジェクトに追加されます。ビルドの最後に、追加されたファイルが解析されます。例えば、

qacli analyze -b makecc -c -ohello\ world.o hello\ world.ccc -ohello\ world hello\
world.o/home/unicorn/sample_projects/Hello World-C/hello world.c - found
'make'コマンドは０を返して実行完了
/home/unicorn/sample_projects/Hello World-C/hello world.c:qac:0:1:0
Progress(Sync Analysis): ................................... done


CMAプロジェクトの解析

CMAプロジェクトの管理 の項で述べたように、Perforce QAC プロジェクトは 'モジュール' として CMA プロジェクトに関連付けることができます。この機能は複数のPerforce QACプロジェクトに解析を実行するために使用できます。

CMAを実行するには、CMA プロジェクト名と、結果が格納されるPerforce QACプロジェクト名を指定します。 

qacli analyze -P <directory> -C <cma-project-name> 

Perforce QACが指定されていない場合は、CMA プロジェクト内のPerforce QAC プロジェクトのリストの最初にあるプロジェクトが使用されます。CMA には、明示的に述べられていない限り、 CMA には暗黙的に指定される
　--file-based-analysis　を除くすべての標準オプショ ンが適用されます。例: 

qacli analyze -P <directory> -C <cma-project-name> -csga

このコマンドは、関連付けられているモジュールを最初に消去した後で、各モジュールに対してフ ァイルベース解析を行い、解析が失敗した場合は停止し、解析されるソースファイルごとにプリ プロセス済みのソースを生成して、解析に失敗したファイルのサポートデータを含むアーカイブを作成します。


Rawソース解析

Perforce QAC プロジェクトに含まれないファイルを解析すると有益な場合があります。例えば設定のデバッグをするためにプリプロセス済みファイルを解析することがあります。その場合は以下のコマンドを実行します。 

qacli analyze -P <directory> --raw-source <file-path> --language-cct <cct-path> 
 
CCTが提供されていない場合は、QAC_Generic_C++.cct がデフォルトで使用されます。
ファイルが省略されていた場合は、'-F'を使用してfilelistを指定することもできます。
ファイルは、解析設定の「解析したファイルのプリプロセス済みソースファイルを生成する」を有効にして生成されたファイルで、'.i'ファイルでなければなりません。

デバッグ解析

C および、C++ に対し、プリプロセス済みソースは、設定とコードのデバッグをする場合に有効です。 Perforce QAC は、以下のプロジェクトの構成ディレクトリにプリプロセス済みソースファイルを生成します。

prqa/configs/<config_name>/output/SOURCE_ROOT

解析されるファイルごとに、プリプロセス済みのソー スファイルを生成するには、以下のオプションを指定します。 

qacli analyze -P <directory> -f --generate-preprocessed-source 

解析設定上の問題によりソースファイルの正常な解析に失敗した場合、情報を収集してのサポートエンジニアまでご連絡下さい。

以下のswitchで、Perforce QAC は、解析に失敗したファイルごとに'.arc' ファイル、'.i'ファイル、'.via' ファイルを含むアーカイブを作成します（これは、QA·GUI オプションの解析エラーが発生したファイルのサポート用情報を収集すると同等です。[解析(N)]メニューの項を参照してください）。

qacli analyze -P <directory> -f --assemble-support-analytics